/*
 * Copyright (C) 2023 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup AVPlayer
 * @{
 *
 * @brief 提供用于播放媒体源的API。
 *
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 11
 * @version 1.0
 */

/**
 * @file avplayer_base.h
 *
 * @brief 定义AVPlayer的结构体和枚举。
 *
 * @kit MediaKit
 * @library libavplayer.so
 * @include <multimedia/player_framework/avplayer_base.h>
 * @since 11
 * @version 1.0
 */

#ifndef MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVPLAYER_BASH_H
#define MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVPLAYER_BASH_H

#include <stdint.h>

#include "native_avformat.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 初始化AVPlayer。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 11
 */
 typedef struct OH_AVPlayer OH_AVPlayer;

/**
 * @brief 播放状态。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 11
 * @version 1.0
 */
typedef enum AVPlayerState {
    /** 空闲 */
    AV_IDLE = 0,
    /** 初始化 */
    AV_INITIALIZED = 1,
    /** 准备 */
    AV_PREPARED = 2,
    /** 播放 */
    AV_PLAYING = 3,
    /** 暂停 */
    AV_PAUSED = 4,
    /** 停止 */
    AV_STOPPED = 5,
    /** 结束 */
    AV_COMPLETED = 6,
    /** 释放 */
    AV_RELEASED = 7,
    /** 错误 */
    AV_ERROR = 8,
} AVPlayerState;

/**
 * @brief 跳转模式。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 11
 * @version 1.0
 */
typedef enum AVPlayerSeekMode {
    /** 同步到时间点之后的关键帧。 */
    AV_SEEK_NEXT_SYNC = 0,
    /** 同步到时间点之前的关键帧。 */
    AV_SEEK_PREVIOUS_SYNC,
    /**
    * @brief 同步到距离指定时间点最近的帧。
    * @since 12
    */
    AV_SEEK_CLOSEST = 2,
} AVPlayerSeekMode;

/**
 * @brief 播放速度。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 11
 * @version 1.0
 */
typedef enum AVPlaybackSpeed {
    /** 0.75倍速播放。 */
    AV_SPEED_FORWARD_0_75_X,
    /** 正常播放。 */
    AV_SPEED_FORWARD_1_00_X,
    /** 1.25倍速播放。 */
    AV_SPEED_FORWARD_1_25_X,
    /** 1.75倍速播放。 */
    AV_SPEED_FORWARD_1_75_X,
    /** 2.0倍速播放。 */
    AV_SPEED_FORWARD_2_00_X,
    /**
     * @brief 0.5倍速播放。
     * @since 12
     */
    AV_SPEED_FORWARD_0_50_X,
    /**
     * @brief 1.5倍速播放。
     * @since 12
    */
    AV_SPEED_FORWARD_1_50_X,
    /**
     * @brief 3.0倍速播放。
     * @since 13
    */
    AV_SPEED_FORWARD_3_00_X,
    /**
     * @brief 0.25倍速播放。
     * @since 13
    */
    AV_SPEED_FORWARD_0_25_X,
    /**
     * @brief 0.125倍速播放。
     * @since 13
    */
    AV_SPEED_FORWARD_0_125_X,
} AVPlaybackSpeed;

/**
 * @brief OnInfo类型。\n
 * 
 * 可用于OH_AVPlayerOnInfoCallback和OH_AVPlayerOnInfo(已废弃)，用于表示收到的播放器信息类型。\n
 * 从API 12开始，推荐用户使用{@link OH_AVPlayerOnInfoCallback}。不同的OnInfo类型，可获取到不同信息（infoBody），infoBody中包含key-value关系表，详见下述枚举值表。\n
 * 使用API 11版本的开发者，需要使用旧接口。针对已废弃接口OH_AVPlayerOnInfo中使用的对应关系，可直接参考{@link OH_AVPlayerOnInfo}的API说明。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 11
 * @version 1.0
 */
typedef enum AVPlayerOnInfoType {
    /** @brief 跳转到对应播放位置时返回消息。\n
      * key为OH_PLAYER_SEEK_POSITION：取值类型int32_t。
      * 系统通过int32_t传递value，应用需通过int32_t获取。
      */
    AV_INFO_TYPE_SEEKDONE = 0,
    /** @brief 播放倍速设置完成时返回消息。\n
      * key为OH_PLAYER_PLAYBACK_SPEED：取值类型{@link AVPlaybackSpeed}。
      * 系统通过int32_t传递value，应用需先通过int32_t获取，再强制转为{@link AVPlaybackSpeed}。
      */
    AV_INFO_TYPE_SPEEDDONE = 1,
    /** @brief 比特率设置完成时返回消息。\n
      * key为OH_PLAYER_BITRATE：取值类型uint32_t。
      * 系统通过int32_t传递value，应用需先通过int32_t获取，再强制为uint32_t。
      */
    AV_INFO_TYPE_BITRATEDONE = 2,
    /** @brief 播放完成时返回消息。 
      */
    AV_INFO_TYPE_EOS = 3,
    /** @brief 状态改变时返回消息。\n
      * key为OH_PLAYER_STATE：取值类型int32_t。
      * 系统通过int32_t传递value，应用需先通过int32_t获取，再强制转为{@link AVPlayerState}。\n
      * key为OH_PLAYER_STATE_CHANGE_REASON：取值类型int32_t。
      * 系统通过int32_t传递value，应用需通过int32_t获取。1：用户操作触发；2：系统变更触发。
      */
    AV_INFO_TYPE_STATE_CHANGE = 4,
    /** @brief 返回当前播放位置。\n
      * key为OH_PLAYER_CURRENT_POSITION：取值类型int32_t。
      * 系统通过int32_t传递value，应用需通过int32_t获取。
      */
    AV_INFO_TYPE_POSITION_UPDATE = 5,
    /** @brief 视频开始渲染时返回消息。\n
      * key为OH_PLAYER_MESSAGE_TYPE：取值类型int32_t。
      * 系统通过int32_t传递value，应用需通过int32_t获取。1表示视频开始渲染。
      */
    AV_INFO_TYPE_MESSAGE = 6,
    /** @brief 音量改变时返回消息。\n
      * key为OH_PLAYER_VOLUME：取值类型float。
      * 系统通过float传递value，应用需通过float获取。取值范围[0.0, 1.0]。
      */
    AV_INFO_TYPE_VOLUME_CHANGE = 7,
    /** @brief 首次获取视频大小或视频大小更新时返回消息。\n
      * key为OH_PLAYER_VIDEO_WIDTH 或 OH_PLAYER_VIDEO_HEIGHT：
      * 取值类型int32_t。系统通过int32_t传递value，应用需通过int32_t获取。
      */
    AV_INFO_TYPE_RESOLUTION_CHANGE = 8,
    /** @brief 返回多队列缓冲时间。\n
      * key为OH_PLAYER_BUFFERING_TYPE：取值类型{@link AVPlayerBufferingType}。
      * 系统通过int32_t传递value，应用需先通过int32_t获取，再强制转为{@link AVPlayerBufferingType}。\n
      * key为OH_PLAYER_BUFFERING_VALUE：取值类型int32_t。
      * 系统通过int32_t传递value，应用需通过int32_t获取。\n
      * 当缓冲更新消息类型是AVPLAYER_BUFFERING_PERCENT、AVPLAYER_BUFFERING_CACHED_DURATION时有效，分别表示缓冲进度完成百分比、缓冲数据可播放时长。
      */
    AV_INFO_TYPE_BUFFERING_UPDATE = 9,
    /** @brief 上报HLS视频比特率列表消息。\n
      * key为OH_PLAYER_BITRATE_ARRAY：取值类型uint8_t字节数组。
      * 应用需要先使用uint8_t类型指针变量保存比特率列表，使用size_t类型变量保存字节数组长度。
      * 然后分配若干个uint32_t类型的存储空间，接收将uint8_t字节数组转换为uint32_t类型比特率整数值。
      */
    AV_INFO_TYPE_BITRATE_COLLECT = 10,
    /** @brief 音频焦点改变时返回消息。\n
      * 取值类型int32_t。系统通过int32_t传递value，应用需通过int32_t获取。\n
      * key为：\n
      * OH_PLAYER_AUDIO_INTERRUPT_TYPE：取值1表示中断事件开始；2表示结束。\n
      * OH_PLAYER_AUDIO_INTERRUPT_FORCE：取值0表示强制打断，系统改变音频播放状态；1表示共享打断，应用改变音频播放状态。\n
      * OH_PLAYER_AUDIO_INTERRUPT_HINT：取值0表示NONE，无提示；1表示RESUME，提示音频恢复；2表示PAUSE，提示音频暂停暂时失去焦点；3表示STOP，提示音频停止；4表示DUCK，音频降低音量；5表示UNDUCK，音频恢复音量。
      */
    AV_INFO_TYPE_INTERRUPT_EVENT = 11,
    /** @brief 返回播放时长。\n
      * key为OH_PLAYER_DURATION：取值类型int64_t。
      * 系统通过int64_t传递value，应用需通过int64_t获取。
      */
    AV_INFO_TYPE_DURATION_UPDATE = 12,
    /** @brief 播放为直播流时返回消息。 
      * key为OH_PLAYER_IS_LIVE_STREAM：取值类型int32_t。
      * 系统通过int32_t传递value，应用需通过int32_t获取。0表示非直播流，1表示直播流。
      */
    AV_INFO_TYPE_IS_LIVE_STREAM = 13,
    /** @brief 轨道改变时返回消息。 
      */
    AV_INFO_TYPE_TRACKCHANGE = 14,
    /** @brief 轨道更新时返回消息。
      */
    AV_INFO_TYPE_TRACK_INFO_UPDATE = 15,
    /** @brief 字幕信息更新时返回消息。
      */
    AV_INFO_TYPE_SUBTITLE_UPDATE = 16,
    /** @brief 音频输出设备改变时返回消息。\n
      * key为OH_PLAYER_AUDIO_DEVICE_CHANGE_REASON：取值类型int32_t。
      * 系统通过int32_t传递value，应用需通过int32_t获取。 
      */
    AV_INFO_TYPE_AUDIO_OUTPUT_DEVICE_CHANGE = 17,
    /**
     * @brief 播放速率成功应用时返回消息。\n
     * key为OH_PLAYER_PLAYBACK_RATE：取值类型float。
     * 系统通过float传递value，应用通过float获取。
     * @since 20
     */
    AV_INFO_TYPE_PLAYBACK_RATE_DONE = 18,
} AVPlayerOnInfoType;

/**
 * @brief 播放缓冲消息类型定义。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
typedef enum AVPlayerBufferingType {
    /** 缓冲开始消息。 */
    AVPLAYER_BUFFERING_START = 1,

    /** 缓冲结束消息。 */
    AVPLAYER_BUFFERING_END,

    /** 缓冲执行进度百分比，取值范围：整数，[0, 100]。 */
    AVPLAYER_BUFFERING_PERCENT,

    /** 缓冲数据可播放时长，单位：毫秒。 */
    AVPLAYER_BUFFERING_CACHED_DURATION,
} AVPlayerBufferingType;

/**
 * @brief 获取播放状态的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_STATE;

/**
 * @brief 获取播放状态变更原因的关键字，对应值类型是int32_t。\n
 * 1：用户操作触发；2：系统变更触发。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_STATE_CHANGE_REASON;

/**
 * @brief 获取音量的关键字，对应值类型是float。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_VOLUME;

/**
 * @brief 获取比特率列表的关键字，对应值类型是uint8_t字节数组。通过该关键字获取信息时：\n
 * 
 * 需要先使用uint8_t类型指针变量保存比特率列表，使用size_t类型变量保存字节数组长度。\n
 * 然后分配若干个uint32_t类型的存储空间，接收将uint8_t字节数组转换为uint32_t类型比特率整数值。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_BITRATE_ARRAY;

/**
 * @brief 获取音频打断类型的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_AUDIO_INTERRUPT_TYPE;

/**
 * @brief 获取音频打断FORCE类型的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_AUDIO_INTERRUPT_FORCE;

/**
 * @brief 获取音频打断HINT类型的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_AUDIO_INTERRUPT_HINT;

/**
 * @brief 获取音频设备变更原因的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_AUDIO_DEVICE_CHANGE_REASON;

/**
 * @brief 获取缓冲更新消息类型的关键字，对应值类型是{@link AVPlayerBufferingType}。\n
 * 通过该关键字获取信息时，需要先使用int32_t类型变量保存结果，再转换为AVPlayerBufferingType类型。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_BUFFERING_TYPE;

/**
 * @brief 获取缓冲更新消息数值的关键字，对应值类型是int32_t，参见{@link AVPlayerBufferingType}。\n
 * 当缓冲更新消息类型是AVPLAYER_BUFFERING_PERCENT、AVPLAYER_BUFFERING_CACHED_DURATION时有效。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 * @version 1.0
 */
extern const char* OH_PLAYER_BUFFERING_VALUE;

/**
 * @brief 获取Seek后播放进度的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_SEEK_POSITION;

/**
 * @brief 获取播放倍速信息的关键字, 对应值类型是{@link AVPlaybackSpeed}。\n
 * 通过该关键字获取信息时，需要先使用int32_t类型变量保存结果，再转换为AVPlaybackSpeed类型。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_PLAYBACK_SPEED;


/**
 * @brief 获取有效播放速率的关键字，对应值类型是浮点数。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 20
 */
extern const char* OH_PLAYER_PLAYBACK_RATE;

/**
 * @brief 获取比特率信息的关键字，对应值类型是uint32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_BITRATE;

/**
 * @brief 获取播放进度信息的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_CURRENT_POSITION;

/**
 * @brief 获取媒体资源时长信息的关键字，对应值类型是int64_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_DURATION;

/**
 * @brief 获取视频宽度信息的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_VIDEO_WIDTH;

/**
 * @brief 获取视频高度信息的关键字，对应值类型是int32_t。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_VIDEO_HEIGHT;

/**
 * @brief 获取播放器消息信息的关键字，对应值类型是int32_t。\n
 * 1：视频帧开始渲染。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_MESSAGE_TYPE;

/**
 * @brief 获取媒体资源是否为直播类型信息的关键字，对应值类型是int32_t。\n
 * 1：直播。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 12
 */
extern const char* OH_PLAYER_IS_LIVE_STREAM;

/**
 * @brief 收到播放器消息时调用。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @param player 指向OH_AVPlayer实例的指针。
 * @param type 信息类型。类型为{@link AVPlayerOnInfoType}，与extra的对应关系可见方法描述。
 * @param extra 其他信息，如播放文件的开始时间位置。
 * @since 11
 * @deprecated since 12
 * @useinstead {@link OH_AVPlayerOnInfoCallback}
 * @version 1.0
 */
typedef void (*OH_AVPlayerOnInfo)(OH_AVPlayer *player, AVPlayerOnInfoType type, int32_t extra);

/**
 * @brief 收到播放器消息时被调用。如果应用成功设置该回调，则不会回调OH_AVPlayerOnInfo函数。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @param player 指向OH_AVPlayer实例的指针。
 * @param type 信息类型。具体请参见{@link AVPlayerOnInfoType}。
 * @param infoBody 指向携带具体消息的指针，仅在该回调方法内有效。
 * @param userData 指向应用调用者设置该回调函数时提供的实例的指针。
 * @since 12
 */
typedef void (*OH_AVPlayerOnInfoCallback)(OH_AVPlayer *player, AVPlayerOnInfoType type, OH_AVFormat* infoBody,
    void *userData);

/**
 * @brief 在API9以上的版本发生错误时调用。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @param player 指向OH_AVPlayer实例的指针。
 * @param errorCode 错误码。\n
 *                  AV_ERR_NO_MEMORY：无内存，取值为1。\n
 *                  AV_ERR_OPERATE_NOT_PERMIT：操作不允许，取值为2。\n
 *                  AV_ERR_INVALID_VAL：无效值，取值为3。\n
 *                  AV_ERR_IO：IO错误，取值为4。\n
 *                  AV_ERR_TIMEOUT：超时错误，取值为5。\n
 *                  AV_ERR_UNKNOWN：未知错误，取值为6。\n
 *                  AV_ERR_SERVICE_DIED：服务死亡，取值为7。\n
 *                  AV_ERR_INVALID_STATE：当前状态不支持此操作，取值为8。\n
 *                  AV_ERR_UNSUPPORT：未支持的接口，取值为9。\n
 *                  AV_ERR_EXTEND_START：扩展错误码初始值，取值为100。
 * @param errorMsg 错误消息。
 * @since 11
 * @deprecated since 12
 * @useinstead {@link OH_AVPlayerOnErrorCallback}
 * @version 1.0
 */
typedef void (*OH_AVPlayerOnError)(OH_AVPlayer *player, int32_t errorCode, const char *errorMsg);

/**
 * @brief 发生错误时被调用。如果应用成功设置该回调，则不会调用OH_AVPlayerOnError函数。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @param player 指向OH_AVPlayer实例的指针。
 * @param errorCode 错误码。\n
 *                  AV_ERR_NO_MEMORY：无内存，取值为1。\n
 *                  AV_ERR_OPERATE_NOT_PERMIT：操作不允许，取值为2。\n
 *                  AV_ERR_INVALID_VAL：无效值，取值为3。\n
 *                  AV_ERR_IO：IO错误。API 12-13取值为4；API 14及以后，对应错误细化为错误码5411001~5411011。\n
 *                  AV_ERR_TIMEOUT：超时错误，取值为5。\n
 *                  AV_ERR_UNKNOWN：未知错误，取值为6。\n
 *                  AV_ERR_SERVICE_DIED：服务死亡，取值为7。\n
 *                  AV_ERR_INVALID_STATE：当前状态不支持此操作，取值为8。\n
 *                  AV_ERR_UNSUPPORT：未支持的接口，取值为9。\n
 *                  AV_ERR_EXTEND_START：扩展错误码初始值，取值为100。
 * @param errorMsg 错误消息。
 * @param userData 原样返回用户设置回调时传入的userData数据。
 * @since 12
 */
typedef void (*OH_AVPlayerOnErrorCallback)(OH_AVPlayer *player, int32_t errorCode, const char *errorMsg,
    void *userData);

/**
 * @brief 包含了OH_AVPlayerOnInfo和OH_AVPlayerOnInfo回调函数指针的集合。
 * 应用需注册此结构体到OH_AVPlayer实例中，并处理回调上报的信息，保证AVPlayer的正常运行。
 * @syscap SystemCapability.Multimedia.Media.AVPlayer
 * @since 11
 * @deprecated since 12
 * @useinstead {@link OH_AVPlayerOnInfoCallback} {@link OH_AVPlayerOnErrorCallback}
 * @version 1.0
 */
typedef struct AVPlayerCallback {
    /**
      * @brief 监控AVPlayer过程信息，参考{@link OH_AVPlayerOnInfo}。
      * @since 11
      * @deprecated since 12
      * @useinstead {@link OH_AVPlayerOnInfoCallback}
      */
    OH_AVPlayerOnInfo onInfo;
    /**
      * @brief 监控AVPlayer操作错误，参考{@link OH_AVPlayerOnError}。
      * @since 11
      * @deprecated since 12
      * @useinstead {@link OH_AVPlayerOnErrorCallback}
      */
    OH_AVPlayerOnError onError;
} AVPlayerCallback;

#ifdef __cplusplus
}
#endif
#endif // MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVPLAYER_BASH_H
